home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / 173autl.zip / MAKEFIDX.DOC < prev    next >
Text File  |  1990-02-24  |  16KB  |  431 lines
  1. MAKEFIDX version 1.1 - An RBBS Utility
  2. by Ken Goosens.  Feb 24, 1990
  3.  
  4. Contents
  5.     0.0  License
  6.     1.0  What is MAKEFIDX?
  7.     2.0  What's New?
  8.     3.0  How to Configure RBBS-PC
  9.     4.0  How to Set Up Downloading for Files Online
  10.     5.0  How to Set Up for Files Offline
  11.     6.0  How to Set Up Macros for Files Online
  12.     7.0  Automating Index Creation
  13.     8.0  Recompiling
  14.     9.0  An Explanation of RBBS-PC's Fast File Search
  15.  
  16.  
  17.                       0.0  Licensing
  18.  
  19. The author does not ask for any donation for use of MAKEFIDX.
  20. The rights to the code are exclusively retained by the author.
  21.  
  22. Everyone is free to use MAKEFIDX without any cost.   Everyone is
  23. free to distribute MAKEFIDX without cost, provided they charge nothing
  24. for MAKEFIDX.  You cannot distribute MAKEFIDX with any shareware or
  25. commercial product without permission of the author.   Modified
  26. versions of MAKEFIDX can be distributed only with permission of the
  27. author.  Enhancements or fixes to the code are welcome.   For
  28. support, the author can be reached on his Bulletin Board at
  29. 703-978-6360.
  30.  
  31.  
  32.                 1.0  What is MAKEFIDX?
  33.  
  34. RBBS-PC, starting with version 17.3, supports a Fast File Search that
  35.   
  36. o   dramatically improves file searches on uploads and downloads
  37.  
  38. o   reduces wear and tear on hard disks
  39.  
  40. o   lets you have over 10,000 download areas
  41.  
  42. o   increases the effective limit on the number of downloadable
  43.     files to 32,767
  44.  
  45. o   introduces "do anything you want" for processing files "off line".
  46.  
  47. MAKEFIDX is a free utility for creating the index files necessary to
  48. implement and support the Fast File Search.   It should be distributed
  49. as FIDX11.ZIP and consists of the following files:
  50.  
  51. MAKEFIDX.EXE - Executable program to make file list and location list
  52. MAKEFIDX.BAS - BASIC source code for MAKEFIDX.EXE
  53. MAKEFIDX.CFG - Sample configuration file for MAKEFIDX.EXE
  54. MASTER.DIR   - Sample master dir of all files you have
  55. DEATHSTR.DIR - Sample list of off line files on another BBS
  56. DISK1.DIR    - Sample list of off line files on disk (restorable)
  57. UNWANT.DIR   - Sample list of unwanted files
  58. SUPPORT.DIR  - Sample list of specially supported products
  59. MAKETABS.EXE - Executable program to make "tabs" file for file list
  60. MAKETABS.BAS - BASIC source coce for MAKETABS.EXE
  61. MAKEFFS.BAT  - Batch file automating processing
  62. MAKEFIDX.DOC - This documentation
  63. DEATHSTR.IMC - Sample macro for files on another BBS
  64. ANOTHBBS.IMC - Sample macro to process requests for files on other BBS's
  65. DISK1.IMC    - Sample macro for files off line on disk 1
  66. OFFLINE.IMC  - Sample macro to process requests for restorable files
  67. CHAIN.IMC    - Sample macro to process requests for pyramid schemes
  68. COMMERC.IMC  - Sample macro to process requests for commercial software
  69. SUPPORT.IMC  - Sample macro for spec msg with supported products
  70.  
  71.  
  72.                    2.0  What's New
  73.  
  74. MAKEFIDX 1.0 was distributed with RBBS-UTL.ZIP as an optional RBBS-PC
  75. utility.  Version 1.1 has the following changes:
  76.  
  77. (a)  There is a new configuration parameter to handle non-standard
  78.      directory listings, so that MAKEFIDX can work just as well for
  79.      4DOS, or any other (see MAKEFIDX.CFG).
  80.  
  81. (b)  Lists of files can now be properly processed.
  82.  
  83. Version 1.0 would not properly handle file lists that included a
  84. drive/path in front of the file, nor lists that had only the file
  85. name on a line, nor would 1.0 properly insert macro processing into
  86. the location file.
  87.  
  88. These changes make it feasible to implement a system for processing
  89. "off line" files, so that download requests for files not really
  90. present and available for downloading can still be processed.
  91. For example, the sysop can now
  92.  
  93. o  keep infrequently downloaded files on backup media, such as
  94.    tapes for diskettes, and restore these files for downloading
  95.    the next day after they are requested.
  96.  
  97. This makes it possible for sysops to make files "available", though
  98. not immediately.   Infrequently requested files can be "archived"
  99. to backup media.   No longer is it necessary to have a gigabyte of
  100. on-line hard disks to have a gigabyte of software available.
  101. Requests for off-line files can be logged and restorals be done
  102. at the sysop's leisure.   Room can be made on the hard disk not
  103. by deleting files from the system but by moving them off-line
  104. but keeping them in the directories.
  105.  
  106. o  keep lists of files available on other BBS's.
  107.  
  108. Essentially, the BBS can become a central resource for informing
  109. callers where to go to get software.  Or, alternative, sysops can
  110. design systems to automatically call other BBS's to download
  111. requested software during the night.  You can do anything you
  112. want with requests for off-line files!
  113.  
  114. o  attach special processing or messages for any file or group
  115.    of files, such as files not wanted.
  116.  
  117. It is also possible to have special processing for "on-line" files
  118. as well.   For example, you may want to
  119.  
  120. o  add a special message for persons downloading "supported" files.
  121.  
  122. You can personalize the messages to in effect attach a note to any
  123. file or group of files, like "SysOp Rates this to be one of the BEST!",
  124. or "Please support Shareware authors!", or to survey what
  125. people are doing with the file -- virtually anything you want.
  126.  
  127.  
  128.             3.0  How to Configure RBBS-PC
  129.  
  130. The Fast File Search requires two parameters to be set up in
  131. RBBS-PC's CONFIG program:
  132.  
  133. 1.  Parmater 267 should give the file name of list of files
  134.     avaliable for downloading.   Recommended name is FIDX.DEF.
  135.     (File InDeX).
  136.  
  137. 2.  Parameter 268 should give the file name of the list of
  138.     locations.  Recommended name is LIDX.DEF (Location InDeX).
  139.  
  140. You need not be concerned at all with the internal structure of
  141. these files.  MAKEFIDX will take care of all of the internals for
  142. you.
  143.  
  144. However, you probably will want to change the way the download
  145. drive/paths are configured.   RBBS-PC will always search its internal
  146. lists first, then search the file index.   To realize the potential
  147. savings in performance, you should reduce the lists of downloadable
  148. areas to at most the upload drive/path, assuming you want uploads to
  149. be available immediately for downloading.   RBBS-PC will treat
  150. everything in the file index to be downloadable, hence you basically
  151. list the downloadable files by file specification in the configuration
  152. for MAKEFIDX and not in the configuration for RBBS-PC.
  153.  
  154.  
  155.         4.0  How to Set up for Downloading Files Online
  156.  
  157. You should first put the files you want to be downloable by themselves
  158. into subdirectories.  You may want to sort them by subjects, but then
  159. you will spend much time just moving uploaded files to download areas.
  160. Most sysops just mix all the different downloadable files into different
  161. drives and subdirectories with no need to the type of file they are.
  162.  
  163. Then you basically tell MAKEFIDX what files are available for downloading
  164. by a standard DOS file specification, which usually consists of a drive and
  165. path, and wildcards.  For example,
  166.  
  167.                      C:\DWN\*.*
  168.  
  169. is all files on drive C, subsdirectory DWN.  Others are:
  170.  
  171.     D:\PICS\*.ZIP   all files on drive D, subdir PICS, with extension ZIP
  172.     C:\RBBS\BULLET* all files on drive C, subdir RBBS, with prefix BULLET
  173.  
  174.  
  175.               5.0  How to Set Up for Files Off Line
  176.  
  177. The configuration option "/FileDir=" is what allows you to add files to
  178. your lists that are off line.   The feature of RBBS-PC that allows
  179. special processing is that the location of the file (in LIDX.DEF)
  180. supports a macro to be executed in place of a file location.   The
  181. format required is
  182.  
  183. M! <macro>
  184.  
  185. For example,
  186.  
  187. M! C:\RBBS\OFFLINE.IMC
  188.  
  189. MAKEFIDX will insert macro processing by including a line at the top
  190. of the FileDir in the format:
  191.  
  192.  Directory of M! <macro>
  193.  
  194. A good way to generate an appropriate file listing is simply to do
  195. a DOS "DIR" with redirection to a file, e.g.
  196.  
  197. DIR A:*.* > DISK1.DIR
  198.  
  199. Then, with an editor, replace the line
  200.  
  201.  Directory of  A:
  202.  
  203. by
  204.  
  205.  Directory of M! DISK1.IMC
  206.  
  207. In MAKEFIDX.CFG, simply have a line
  208.  
  209. /FileDir=DISK1.DIR
  210.  
  211. MAKEFIDX will put into LIDX.DEF whatever occurs after "Directory of"
  212. and will take it to be the location of all the file names that follow
  213. that line.
  214.  
  215. By the way, the extension "IMC" stands for "Internal MaCro".   Any other
  216. could be used.   It is suggested merely to be different from the standard
  217. user invoked macro extension of "MCR" so that an internal macro can
  218. never be accidentally invoked by a user.
  219.  
  220. A Fast File Search macro will be invoked whenever a fast file search
  221. is done, which includes downloads, uploads, and view archives.   You may
  222. want to have different processing for each of these cases.  RBBS-PC 17.3A
  223. up puts in work variable one (referenced by "[1]") a "D", "U", or "V"
  224. respectively for download, upload, and view, so you can use the macro
  225. case logic to treat each invocation differently.
  226.  
  227. The macro file DISK1.IMC might then contain
  228.  
  229. 1
  230. {ON 1
  231. {==U
  232. {*B
  233.  
  234.     The file {FI is stored {C1offline{C0.
  235.     Please do not upload it.
  236.  
  237. {END ON
  238. {:= 2 #1
  239. {M! OFFLINE.IMC
  240.  
  241.  
  242. The second line basically sets an identifier for the appropriate back
  243. up source to be used.
  244.  
  245. The macro in turn invoked, OFFLINE.IMC, might contain
  246.  
  247. 1
  248. {*B
  249.  
  250.  
  251.      The file {FI is {C1not available{C0 immediately, but is
  252.      stored {C1off line{C0 and can be {C2restored{C0 for you by
  253.      the SysOp within 24 hours.
  254.  
  255. {END
  256. {TK
  257. {01Request that the sysop restore the file (Y,N)
  258. {ON 1
  259. {==Y
  260. {>> C:\RBBS\PLZRESTR.DAT
  261. {FI from [2] for {FN {LN, {DT {TM
  262. {END
  263. {*1 Please check back tomorrow for {FI
  264. {END ON
  265.  
  266. This simply logs to file PLZRESTR.DAT requests to store the file.
  267. Note that the log gives with file name, disk id to restore from,
  268. and who make the request when, using RBBS-PC's work variables and
  269. SmartText variables.
  270.  
  271.  
  272.          6.0  How to Set Up Macros for Files Online
  273.  
  274. A macro in the Fast File Search substitutes for a location in the
  275. Location Index LIDX.DEF.   Hence, macros imply that the file has
  276. no location and is therefore not found.  However, you can in the
  277. macro itself supply a location for the file, using the macro command
  278. "{LO <drive/path>".  E.g.
  279.  
  280. {LO C:\SUPPORT\
  281.  
  282. tells RBBS to look in the drive/path C:\SUPPORT\ for the file
  283. that has the invoked macro for its "location" (just as if the location
  284. file had C:\SUPPORT\ in it instead of the macro).
  285.  
  286. Files you want to process this way MUST NOT be in any of the downloadable
  287. "/FileSpec=" given early, because then the file will have a location.
  288. Instead, use the "\FileDir" and process these files the same as off-line.
  289. The only difference is that the macro invoke supplies the location.
  290. Note:  you must manually update the macro if you move the file.   For
  291. example, suppose you want to put up a special message of support for
  292. everyone downloading the executable files for RBBS-PC.   Then you have a
  293. SUPPORT.DIR file with
  294.  
  295.  Directory of SUPPORT.IMC
  296. RBBS-EXE.ZIP  Specially supported files.  Location give in macro.
  297.  
  298. and the macro SUPPORT.IMC says
  299.  
  300. 1
  301. {ON 1
  302. {==D
  303. {*B
  304.  
  305.      Thanks for downloading {FI from a {C1SUPPORT BOARD{C0
  306.      for the product.   You can reach me voice in the evenings
  307.      at (xxx) 123-4567 if need any help with it.
  308.  
  309. {END
  310. {END ON
  311. {LO C:\RBBS\
  312.  
  313. The last line in the macro tells RBBS-PC to look for RBBS-EXE.ZIP in
  314. drive/path C:\RBBS\.
  315.  
  316.  
  317.              7.0  Automating Index Creation
  318.  
  319. The process of maintaining a list of files for the RBBS-PC Fast File
  320. Search can be automated.  MAKEFFS.BAT is an example of a batch file
  321. automating this process.   The steps are:
  322.  
  323. 1.   Create a list of files not online but to be added to the Fast
  324.      File Search.   The substeps in this process are:
  325.  
  326.      a.  keep a list of all of the on-line files on your system, e.g.
  327.          MASTER.DIR.   Put this is the master list in CMPBBS.CFG.
  328.  
  329.      b.  keep lists of all additional new files to be added to the
  330.          fast file system.  Set them to "AddList"s in CMPBBS.CFG.
  331.          Be sure to put in a header specifying a macro to execute.
  332.  
  333.      c.  Run CMPBBS to create a list of new files to add.   Put this
  334.          new file list in as a "FileDir" in MAKEFIDX.CFG.
  335.  
  336. 2.   Set up MAKEFIDX.CFG to refer by filespec to include all
  337.      downloadable files (except those in the upload directory).
  338.  
  339. 3.   Run MAKEFIDX to create both a combined list of all files on
  340.      and offline, and well as a location file.
  341.  
  342. 4.   Sort the combined list of files (FIDX.DEF) on the file name.
  343.  
  344. Note:  step 4 is set up in the batch file to use the shareware
  345. program QSORT, which is not provided.   Any good sorting program
  346. can be used instead.
  347.  
  348. 5.   Run MAKETABS to produced an index on the sorted file list to
  349.      further speed up searches.
  350.  
  351.  
  352.                       8.0  Recompiling
  353.  
  354. MAKEFIDX and MAKETABS are written in Basic for MicroSoft's
  355. QuickBasic, and will compile in 4.5 up.
  356.  
  357. The commands to recompile are:
  358.  
  359. BC MAKEFIDX /O/X;
  360. LINK MAKEFIDX;
  361.  
  362. BC MAKETABS /O/X;
  363. LINK MAKETABS;
  364.  
  365.  
  366.        9.0  An Explanation of RBBS-PC's Fast File Search
  367.  
  368. For directories DOS uses chained "buckets" in multiple locations, 
  369. searched sequentially.   This results in very slow performance when
  370. the number of files to search gets into the thousands.   RBBS now
  371. supports a fast file search than more than compensates for the
  372. inefficent operation in DOS.
  373.  
  374. The basis for the fast file search is a file, configuration
  375. parameter 267, which is a sorted list of file names available for
  376. downloading.    The default name is FIDX.DEF.
  377.  
  378. The format of this file is:
  379.  
  380. columns 1-12:  file name
  381. columns 13-16: location index (1, 2, 3, ...)
  382. columns 17-18: carriage return line feed.
  383.  
  384. All data is stored as character data and the file is editable.   The file
  385. names must be stored with no internal spaces and a period separating the
  386. prefix from the extension.   The list of file names MUST BE SORTED BY
  387. FILE NAME in order for the fast file search to work.
  388.  
  389. The location index is the record number (line number) of the locator file,
  390. whose default name is LIDX.DEF, and has the following layout:
  391.  
  392. columns 1-63:  location of file
  393. column  64:    any character.  MAKEFIDX puts in a period.
  394. columns 65-66: carriage return line feed.
  395.  
  396. This file is all character data and is editable.   Essentially, the location
  397. index points to a record in the location file.   E.g. if FIDX.DEF has
  398.  
  399. RBBS-BAS.ZIP   2
  400. HARPIE.ARC     3
  401.  
  402. and LIDX.DEF has
  403.  
  404. C:\DOWN1\
  405. C:\DOWN2\
  406. C:\UP\
  407.  
  408. Then RBBS-BAS.ZIP is located in directory C:\DOWN2 (2nd record) and 
  409. HARPIE.ARC is located in C:\UP (3rd record).
  410.  
  411. The location field should be a drive/path terminating with a "\" if
  412. any path is given, and file must be filled with blanks through column
  413. 63 if the path is shorter.  You must put some character in column 64.
  414. Many editors delete trailing blanks, so you should probably put in
  415. a non-blank.  A period is a suitable choice.
  416.  
  417. RBBS will use a binary search on the first 12 characters in FIDX.DEF.
  418. This binary search can be significantly speeded by provided "tabs" for
  419. this file, indicating the record at which the first file is that begins
  420. with the symbols "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ".   This is like
  421. the "tabs" you see on dictionaries, so you can directly turn to the B's,
  422. for example.   A tab file has the same prefix as the file name file,
  423. except that it adds a "T".  For "FIDX.DEF", the tab file would be
  424. "FIDXT.DEF".   RBBS will automatically detect and use a tab file if
  425. available.   The tab has 72 characters in it.   Each 2 bytes represents
  426. a binary integer whose value is the record number in FIDX.DEF where the
  427. first file occurs that begins with the respective symbols above.  Thus
  428. bytes 3-4 show where files begin with "1" and bytes 69-70 where files
  429. begin with "Y".
  430.  
  431.